Setting up version control

1 Why version control?

If an analysis was published and changes were made to the analysis script, we won’t be able to easily reproduce those results without knowing what was done to the script! GitHub provides us some safety for reproducibility by tracking changes to a shared repository. Even if someone deletes code from a file, we can revert to a previous version of the shared repository. Note that we’re not saving data to the repository, so make sure the file used lives where the script says.

We’re also able to review changes people make before they’re accepted to GitHub, which allows us to provide some quality control in the analyses we intend to publish.

2 High level overview

At a high level, GitHub is a tool that allows us to collaboratively track, manage, and use files. We clone a GitHub repository to our computer, and changes to those files on our computer are detected by Git, the underlying versioning software. We can upload those changes to GitHub, which tracks and shares what changes were made. The ‘Master” branch you see below is what is on GitHub. When you clone the repo to your computer, you’ll be cloning the master branch, and any changes you make will fork (see blue). People won’t see your changes until you commit to your cloned/local repository and ’push’ your changes back to the master branch. In order for someone to see your recently pushed changes, they need to pull after your changes are pushed to master. For example, Orange won’t see the changes Blue made because Orange didn’t pull from the master branch after Blue committed & pushed their changes back to the master branch.

If we want to implement a stricter standard of quality control, we can alternatively create a branch from master and request others to review our code using a ‘pull request.’ This would require others to review our code before our work is ‘pulled’ back into master. The diagram below still works. Though, instead of us pushing our forked changes to master, we’re explicitly creating a branch and requesting people to approve our changes and pull it back into master, rather than (implicitly) forking off master and pushing our changes back without review.

3 Getting set up

By now, you should have received an invite from our Enterprise GitHub to collaborate on the on a specific repository. Once you create an account, you will be able to access the GitHub repository. The one shown below is the hillblom_data repo, which is now renamed.. That should look like this:

Once you have your account set up and are able to access the link provided above to navigate to the specific repository, it’s time to download the GitHub Desktop App.

After the GitHub app is downloaded, go to back to the repository. From there, you’ll click the green button, ‘Code.’

And click, ‘Open with GitHub Desktop.’

That’ll open the GitHub App (if you approve permission), and you’ll be greeted with this screen. Set the local path to whichever folder you want to work from. For this iteration, I created an ‘Enterprise’ folder. Though, I’m typically working from my Documents folder.

The final local path should be something similar to :

• on Mac: /Users/yourusername/Documents/reponame
• on PC: C:Users\yourusername\Documents\reponame

From here, hit ‘Clone.’

4 Test it out!

4.1 Open the local directory where you cloned the repository

4.2 Find the file ‘write_your_name.txt’ in the path:

• on Mac: /Users/yourusername/Documents/reponame
• on PC: C:Users\yourusername\Documents\reponame

4.3 Write your name.

4.4 Close the file.

4.5 Open the GitHub App.

4.6 Pull/fetch the most recent version of the master branch.

• This is to ensure we are working from the most recent version of the master branch.

4.7 Commit changes to your local machine.

• This records changes you made to the cloned version of the repository.
• If left after this stage, people will not see your changes in the shared repository.

4.8 Finally, push your changes.

Now everyone can see your changes on the Github website or on their local machine if they pull/fetch. We’re able to track what changes were made and refer or revert back to previous versions of the files in the repository.

5 For more stringent quality control

5.1 Create a new branch

• Click on the current branch.

• Opt to create new branch

• Name branch and confirm

5.2 Publish the new branch to our GitHub repo.

5.3 Now you can work in this branch as you would the original.

• Your changes will be tracked, and you will need to commit your changes to the branch you’re working on.

• Commit your changes to your local version of the branch

• Push your changes to the online repository

5.4 When you’re ready for someone to review your code and merge the branch you created back to the origin, create a pull request.

• This will take you to the GitHub website, where you’ll assign your reviewers and assignees. They’ll be the ones who review your code. Leave a brief description of your request and a more detailed explanation below if needed.

5.5 If you were assigned to a pull request, you’ll see these pages.

• First, it’ll take you to the conversation page. However, you’ll want to take a look at the changes you’ve been assigned to review, which you can find in the ‘Files changed’ tab.
• You’ll see the only change in this file was an added space. Additions are in green, and deletions/old code are in red.
• Go to the ‘Review changes’

• Leave you comments, requests, or approve the pull request.

5.6 Once your pull request is approved, merge the pull request back into the origin.

• Confirm the merge.

5.7 Finally, you can delete the old branch.

• This isn’t necessary, but it can help to keep things organized.

6 That’s the end!